---

QuickTime Streaming

| Previous | Chapter Contents | Chapter Top | Next |

How to Find a Sample Using the Sample Table Atom

Before we dive into the structural details of the sample table child atoms, you might want to know how they're used. You'll need to examine the structure of the child atoms in detail to implement an actual algorithm.

Let's assume you know what the current movie time is and you want to find the appropriate hint sample to packetize some movie data. Here are the steps you take:

Begin by converting the movie time into timescale units for this hint track. Note: Time scale for the track is in the media handler header ( 'mdhd' ) atom.

Look in the time-to-sample atom ( 'stts' ) to determine which sample corresponds to the target time. The time-to-sample atom contains a table of samples and durations. You need to do some integer arithmetic to calculate the sample number from the time.

Once you have the sample number, use the sample-to-chunk atom to find out what chunk it's in. The sample-to-chunk atom contains a table listing chunks and samples-per-chunk. You need to do some integer arithmetic to calculate the chunk number from the sample number. You also need to do some modulo arithmetic to calculate which sample within that chunk is the one you want.

Find out where the chunk starts by looking in the chunk offset table atom ( 'stco' ). It's a simple table with the byte offset of each chunk. Note: The byte offset is into the file or resource specified by the data reference atom ( 'dref' ) inside the data information atom ( 'dinf' ).

Use the sample sizes atom ( 'stsz' ) to determine the byte offset within the chunk for your sample. The sample sizes atom contains either a number (the sample size, if all samples are of equal size) or a table with the size of each sample. You need to sum the size of every sample in your chunk prior to your target sample to obtain the byte offset of your sample within the chunk.

Add the byte offset of your sample to the byte offset of the chunk. That's where your hint track sample begins.

Now let's look at the sample table child atoms individually. Refer to the QuickTime File Format documentation for the structural details of each atom type.

Sample Description Atom ( 'stsd' )

The sample description atom ( 'stsd' ) contains information about the hint track samples. It specifies the data format (currently only RTP data format is defined) and which data reference to use (if more than one is defined) to locate the hint track sample data. It also contains some general information about this hint track, such as the hint track version number, the maximum packet size allowed by this hint track, and the RTP timescale. It may contain additional information, such as the random offsets to add to the RTP time stamp and sequence number.

The sample description atom can contain a table of sample descriptions to accomodate media that are encoded in multiple formats, but a hint track can be expected to have a single sample description at this time.

The sample description for hint tracks is defined below.

Table 1 Hint track sample description

Field	Bytes
Size	4
Data format	4
Reserved	6
Data reference index	2
Hint track version	2
Last compatible hint track version	2
Max packet size	4
Additional data table	variable

Size

A 32-bit integer specifying the size of this sample description in bytes

Data format

A four-character code indicating the data format of the hint track samples. Only 'rtp ' is currently defined. Note that the fourth character in 'rtp ' is an ASCII blank (hex 20). Do not attempt to packetize data whose format you do not recognize.

Reserved

Six bytes that must be set to 0.

Data reference index

This field indirectly specifies where to find the hint track sample data. The data reference is a file or resource specified by the data reference atom ( 'dref' ) inside the data information atom ('dinf') of the hint track. The data information atom can contain a table of data references, and the data reference index is a 16-bit integer that tells you which entry in that table should be used. Normally, the hint track will have a single data reference, and this index entry will be set to 0.

Hint track version

A 16-bit unsigned integer indicating the version of the hint track specification. This is currently set to 1.

Last compatible hint track version

A 16-bit unsigned integer indicating the oldest hint track version with which this hint track is backward-compatible. If your application understands the hint track version specified by this field, it can work with this hint track.

Max packet size

A 32-bit integer indicating the packet size limit, in bytes, used when creating this hint track. The largest packet generated by this hint track will be no larger than this limit.

Additional data table

A table of variable length containing additional information. Additional information is formatted as a series of tagged entries. This field always contains a tagged entry indicating the RTP timescale for RTP data. All other tagged entries are optional. Three data tags are currently defined for RTP data. One tag is defined for use with any type of data. Additional tags can be created by developers. Tags are identified using four-character codes. Tags using all lowercase letters are reserved by Apple. Ignore any tagged data you do not understand. Table entries are structured like atoms. The structure of table entries is shown below.

Field	Format	Bytes
Entry length	32-bit integer	4
Data tag	4-char code	4
Data	variable	Entry length - 8

Tagged entries defined for 'rtp ' data format:

Data Tag

Data Format

'tims'

32-bit integer specifying the RTP timescale. This entry is required for RTP data.

'tsro'

32-bit integer specifying the offset to add to the stored timestamp when sending RTP packets. If this entry is not present, a random offset should be used, as specified by the IETF. If this entry is 0, use an offset of 0 (no offset).

'snro'

32-bit integer specifying the offset to add to the sequence number when sending RTP packets. If this entry is not present, a random offset should be used, as specified by the IETF. If this entry is 0, use an offset of 0 (no offset).

Tagged entries defined for any data format:

Data Tag

Data Format

'rely'

8-bit flag indicating whether this track should or must be sent over a reliable transport, such as TCP/IP. If this entry is not present, unreliable transport should be used, such as RTP/UDP. The current client software for QuickTime streaming will only receive streaming tracks sent using RTP/UDP. Bits 0-5 (hex 0-3F) are reserved, and must be false . Bit 6 true (40 hex) indicates reliable transport preferred. Use TCP/IP if available, RTP/UDP otherwise. Bit 7 true (80 hex) indicates reliable transport is required. Use TCP/IP if available. Do not send this track over RTP/UDP.

Time-to-Sample Atom ( 'stsd' )

The time-to-sample atom ( 'stsd' ) for hint tracks is used normally, as described in the QuickTime File Format documentation (Movie Atoms section, Sample Atoms subsection). It contains a table you can use to determine which hint track sample corresponds to what time in the movie.

Synch Samples Atom ( 'stss' )

The synch samples atom ( 'stss' ) for hint tracks is used normally, as described in the QuickTime File Format documentation (Movie Atoms section, Sample Atoms subsection). It contains a table listing the samples that can be used for random access into the movie (key frame samples). This atom is optional. If it is not present, all sample frames can be used as key frames for this track.

Sample-to-Chunk Atom ( 'stsc' )

The sample-to-chunk atom ( 'stsc' ) for hint tracks is used normally, as described in the QuickTime File Format documentation (Movie Atoms section, Sample Atoms subsection). It contains a table you can use to determine which chunk contains a particular sample.

Sample Sizes Atom ( 'stsz' )

The sample sizes atom ( 'stsz' ) for hint tracks is used normally, as described in the QuickTime File Format documentation (Movie Atoms section, Sample Atoms subsection). If all the samples are the same size, it holds the size in bytes as a 32-bit integer. Otherwise, it contains a table you can use to determine the size of any sample. You need to use this data to determine the byte offset of a given sample within a chunk.

Chunk Offset Table Atom ( 'stco' )

The chunk offset table atom ( 'stco' ) for hint tracks is used normally, as described in the QuickTime File Format documentation (Movie Atoms section, Sample Atoms subsection). It contains a table with the byte offset of each chunk. The offset is into a file or resource specified indirectly by the data reference index field of the hint track sample description atom ( 'stsd' ). The actual data reference is in the data reference atom ( 'dref' ) inside the hint track's data information atom ( 'dinf' ).